MacWorld 1998 September/Macworld (1998-09).dmg/Shareware World/Info/For Developers/MacZoop 1.8.3/More Classes/File Classes/ZBlockFile.h

Text File | 1997-03-05 | 5KB | 162 lines

/*************************************************************************************************
*
*
*            ObjectMacZapp        -- a standard Mac OOP application template
*
*
*
*            ZBlockFile.h        -- a generic file object that includes some basic block
*                                    management facilities. This type of file is useful for
*                                    implementing VM schemes and databases, etc.
*
*
*            © 1996, Graham Cox
*
*
*
*
*************************************************************************************************/

#pragma once

#ifndef __ZBLOCKFILE__
#define __ZBLOCKFILE__


#include    "ZFile.h"


class    ZArray;


class    ZBlockFile    : public ZFile
{
protected:
    ZArray*        bmap;
    long        refSeed;
    long        useCount;

public:
    ZBlockFile( const FSSpec& aFileSpec );
    ZBlockFile( Str255 fName );
    ~ZBlockFile();

// overrides:

    virtual void            Open();
    virtual void            Close();

// specific to this class:

    virtual long            AddBlock();
    virtual void            AddBlockUsingRef( const long aRef );
    virtual void            RemoveBlock( const long ref );

    virtual void            GetBlockData( const long ref, void* dataPtr, long* dataLen );
    virtual void            GetBlockData( const long ref, Handle dataH );

    virtual void            SetBlockData( const long ref, void* dataPtr, long dataLen );
    virtual void            SetBlockData( const long ref, Handle dataH );

    virtual long            GetNewRefSeed() { return ++refSeed; };
    virtual long            GetBlockCount();
    virtual long            GetBlock( const long ref );
    virtual long            GetBlockRef( const long bkIndex );
    virtual unsigned long    GetBlockSize( const long bkIndex );

protected:

    virtual void            AppendBlock( const long ref, const unsigned long sizeNeeded );
    virtual long            FindFreeBlock( const unsigned long sizeNeeded );
    virtual void            FreeBlock( const long bkIndex );
    virtual void            SplitBlock( const long bkIndex, const unsigned long bkSize );
    virtual void            ReallocBlock( const long ref, long newBkSize );
    virtual void            SetMarkToBlock( const long bkIndex );

    virtual void            ReadMap() {};
    virtual void            WriteMap() {};
    virtual void            InitMap();
    virtual void            WriteHeader() {};

    virtual void            CompactMap();
    virtual void            CompactFile() {};
};

// we force 68k alignment for when the map is stored in the file- the file will work
// on either platform.

#if PRAGMA_ALIGN_SUPPORTED
#pragma options align=mac68k
#endif

// block status:

typedef enum
{
    free,
    notFree
}
BlockStatus;


// this is what is stored in the <bmap> array, one for every block in the file:

typedef struct
{
    long            fRefNum;
    unsigned long    fMark;
    unsigned long    fSize;
    BlockStatus        fStatus;
}
Block;

#if PRAGMA_ALIGN_SUPPORTED
#pragma options align=reset
#endif

// possible errors:

enum
{
    kBlockFileNotOpenErr    = 257,
    kBlockBadRefErr,
    kBlockNotFoundErr,
    kBlockDupRefErr,
    kBadSplitReqErr
};

/*

This object is a file which is subdivided into a sequence of multiple blocks. This is useful
when you want to store in a single file a lot of different things. Each item in the file must
have a unique "block reference number", which can be allocated sequentially from a seed if
you desire. Otherwise, for temporary files, you could use an object address- as long as the
value is unique it doesn't matter. You can then get and set the block's data at any time- this
object looks after where it is stored in the file. Before you can do this, you must register
the block refnum using AddBlock(). This creates an entry in the map table referring to this
block. If you no longer need the block, calling RemoveBlock() will free the space in the file
for other's use.

If you want to use this class for permanent files, the map itself must be saved in the file
and recovered when it is opened. To do this, you must override WriteHeader, WriteMap and
ReadMap. The header should generally include an offset to the start of the map so that you can
read it back into memory.

The methods in this object manage the filespace reasonably efficiently, but never split data
into non-contiguous segments. Thus the file will grow but not automatically shrink (though
freed space is always re-used where possible for new data). To shrink the file, you can call
CompactFile(), which will remove all unused space. This may take a while due to the amount of
data movement needed on disk, and uses a progress bar. CompactMap() is a much faster operation
which conjoins all adjacent free blocks into larger ones, thus making the reuse of such parts
of the file much more likely. This is called internally and you shouldn't need to call it
yourself.

This object makes no assumptions whatever about the data you store- as long as you supply its
total size in bytes, it will store and return it to you. You are free to change the size once
the block is written- the position within the file where the data is saved is automatically
managed so that you can always retrieve it and that freed space becomes available for new data.

*/


#endif